\thispagestyle{empty} 

\begin{center}
  
% Upper part of the page
% erdapfel logo 
\includegraphics{ico/eps/ic_launcher.eps}\\[1cm]
 
\rule{\linewidth}{0.2mm}\\[0.2cm]
\textsc{\LARGE erdapfel}\\
\rule{\linewidth}{0.2mm}\\[2.5cm]

\textsc{\Large Enhanced Android map viewer User's Guide}\\[0.4cm]
  
% Rols
\begin{minipage}{\textwidth}
\begin{flushright} \large
\emph{By:} Adrià Ribatallada Torelló \\
\end{flushright}
\end{minipage}
 
%emplena d'espais buits fins al final de la pàgina
\vfill
 
% Peu de pàgina (data)
{\large \today}
 
\end{center}


\subsubsection{Overview}

        The erdapfel Android application is a test program to display, manage
        and edit maps.
\\
        It's intended to demonstrate the capabilities of the mapsforge-gml-kml 
        library, which is an enhancement of the regular mapsforge library with 
        gml and kml file support.
\\

\subsubsection{Installing}

	The package erdapfel.apk requires a minimum Android version 2.1 Eclair 
        (API level 7), 
\\
        To allow on device .map file generation you have to install the 
        additional package mapfile-writer4and.apk, which requires minimum
        Android version 2.3.3 Gingerbread (API level 10), and a minimum of
        128 Mb of virtual machine heap memory (high-end device).
\\
        Once installed, you can configure the settings of the application to 
        fit your device needs.

\subsubsection{settings menú}
	The settings menú contains the following configuration options:

\begin{itemize}
	\item{$-$} Fullscreen: If enabled the main screen should cover the 
        whole device screen space. If disabled, the main Android task bar will 
        remain visible. This options requires a program restart.
	\item{$-$} Layers Save Folder: Specifies the location where the layers 
        saved using the ``Save Layers'' option should be stored. We recomend 
        somewhere in the external storage (default value is \url{/mnt/sdcard/download/out})
\end{itemize}

\begin{figure}[!ht]
  \centering
        \includegraphics[width=0.8\textwidth]{misc/erdapfel09.eps}
  \caption{settings screenshot}\label{man-erdapfel09}
\end{figure}

\FloatBarrier
\subsubsection{main screen}
	The main screen displays a map and allows some operations over it.

\begin{figure}[!ht]
  \centering
        \includegraphics[width=0.8\textwidth]{misc/erdapfel02.eps}
  \caption{map screenshot}\label{man-erdapfel02}
\end{figure}

        You can interact with that map with the touchscreen. Dragging the 
        finger through the screen will allow you to move the map area displayed,
        and will also show for a short time some buttons (which will disappear 
        after certain amount of time showing the whole map on the screen again).
\\        
        The buttons displayed over the map are the following:

\begin{itemize}
	\item{$-$} PolygonMode: enables polygon edition mode.
	\item{$-$} MetricsMode: enables distance measurement and area 
        calculation mode.
        \item{$-$} Clear: Clears all the user generated polygons 
        (but leaves the map).
        \item{$-$} ZoomControls: increase or decrease the zoom level.
\end{itemize}

\begin{figure}[!ht]
  \centering
        \includegraphics[width=0.8\textwidth]{misc/erdapfel01.eps}
  \caption{map with visible buttons}\label{man-erdapfel01}
\end{figure}

        Additional options may be accessed when the Android Menú button is 
        pressed. These options are:

\begin{itemize}
	\item{$-$} Save Offline Map: Save the desired zone as a local mapfile (requires mapfile-writer4and application).
	\item{$-$} Load Offline Map: Load a mapfile (.map).
	\item{$-$} Load/Add Layer: Load a GML or KML file as a layer (and add it to the map).
	\item{$-$} Save Layers: Save the user generated polygons as a kml file.
	\item{$-$} Settings: Access the settings screen.
\end{itemize}

\begin{figure}[!ht]
  \centering
        \includegraphics[width=0.8\textwidth]{misc/erdapfel08.eps}
  \caption{map with visible menú}\label{man-erdapfel08}
\end{figure}

        By default, when the application starts, it tries to load a tile map 
        from the internet, if no internet connection is available, you can still
        load an offline map using the appropriate menú option.

\FloatBarrier
\subsubsection{offline map loading}

        When the ``Load Offline Map'' option is selected from the menú, a file browser appears and lets you navigate through the android file system and choose a valid .map file to load.
\\
        Once the file is selected, the file browser disappears and the map is loaded in the main map view, overwriting whatever map was displayed previously and centring the view as the new .map file specifies.

\begin{figure}[!ht]
  \centering
        \includegraphics[width=0.8\textwidth]{misc/erdapfel10.eps}
  \caption{file picker}\label{man-erdapfel10}
\end{figure}

\FloatBarrier
\subsubsection[offline map generation]{offline map generation (with mapfile-writer4and app)}
        This option only works when online, and it's intended to work with the mapfile-writer4and app to generate map files using the Android device. 
\\
        When the option is selected from the menu, the map scrolling is dasabled, and instead the user input allows the user to select a rectangular area, which will be the stored map.
\\
        Note that sue to limitations with the OpenStreetMap servers, if the area selected is too big, this operation will fail.
\\
        Once the area is selected you can double-tap on the screen, and this will trigger the actual downloading of osm data and generation of the .map file.
\\
        This .map file generation requires that the mapfile-writer4and application is present in the system, if it is, then this process calls it and generates a new map file with the specified location.
\\
        Beware! this feature requires a high end device with a great amount of Dalvik Java heap memory (more than 128Mb).

\FloatBarrier
\subsubsection{polygon drawing}
        When the polygon drawing button is pressed, the application changes to polygon draw mode and the user input behaviour is changed.
\\
        You will always know that you are in polygon draw mode, for the green text on top of the map.
\\
        In this operation mode the ``slippy'' map and zoom controls are locked, so make sure that the whole area where you want to draw is on screen before starting this mode.
\\
        In polygon draw mode whenever the screen is pressed you add a new polygon vertex. You can also edit an existing vertex position by dragging it. 

\begin{figure}[!ht]
  \centering
        \includegraphics[width=0.8\textwidth]{misc/erdapfel05.eps}
  \caption{polygon draw screenshot}\label{man-erdapfel05}
\end{figure}

        A polygon is ``completed'' by joining the last vertex inserted with the first, thus closing the polygon, converting it to an actual layer over the map, and exiting the drawing mode.

\begin{figure}[!ht]
  \centering
        \includegraphics[width=0.8\textwidth]{misc/erdapfel06.eps}
  \caption{polygon closing}\label{man-erdapfel06}
\end{figure}

\begin{figure}[!ht]
  \centering
        \includegraphics[width=0.8\textwidth]{misc/erdapfel07.eps}
  \caption{polygon closed}\label{man-erdapfel07}
\end{figure}

        You can also erase the last inserted vertex if you make a mistake by pressing the ``back'' Android button.
\\
        If all the vertexes are removed the application exits polygon draw mode and returns to the main map view mode.

\FloatBarrier
\subsubsection{metrics mode}
        The metrics mode is similar in operating to the polygon drawing mode.
\\
        In this case, the displayed text that lets you know you are in metrics mode, is light blue.
\\
        Whenever two vertexes are inserted in this mode, the approximate distance between points is painted over the line between the vertexes.

\begin{figure}[!ht]
  \centering
        \includegraphics[width=0.8\textwidth]{misc/erdapfel03.eps}
  \caption{distance between points}\label{man-erdapfel03}
\end{figure}

        Please, note that this distance calculation is only an approximation and doesn't account for height or terrain irregularities.
\\
        If more than 2 vertexes are inserted, an approximate area calculation for the polygon represented is displayed on top of the screen.

\begin{figure}[!ht]
  \centering
        \includegraphics[width=0.8\textwidth]{misc/erdapfel04.eps}
  \caption{area calculation}\label{man-erdapfel04}
\end{figure}

        This area approximation uses a simple area calculation algorithm and does not consider earth curvature nor geographical accidents. It also fails for cross intersecting polygons, so beware.

\FloatBarrier
\subsubsection{layer loading}
        The layer adding/loading option opens a file browser (like the one for map loading) that let's you choose a GML/KML file.
\\
        Once selected, if the file can be understood by erdapfel its contents will be added as a layer on top of the currently displayed map.
\FloatBarrier
\subsubsection{layer saving}
        This option allows to save all the generated polygons and loaded layers to a single kml file.
\\
        This file is placed under the folder specified in the settings screen.
\FloatBarrier
\subsubsection{invocation through Intents}
        It is possible to call erdapfel from another application via intents.
\\
        When doing so the application can be launched with parameters telling what Map file and/or Layer files to display.
\\
        This is done by putting extra parameters in the Intent, here's an example: 

\begin{verbatim}
PackageManager pm = getPackageManager();
Intent intent = pm.getLaunchIntentForPackage("edu.fib.upc.erdapfel");
if (intent == null) throw new PackageManager.NameNotFoundException();
intent.putExtra("KMLFile","MyFile");
startActivity(intent);
\end{verbatim}

        For more information on the supported parameters and its syntax please read the technical documentation of erdapfel.
\FloatBarrier
\subsubsection{License}

	This program is under GPL license.

\FloatBarrier
\subsubsection{Contact}

Adrià Ribatallada Torelló
adria.ribatallada@est.fib.upc.edu

%emplena d'espais buits fins al final de la pàgina
\clearpage
\vfill
